feat: add support for adding labels to captured errors #1594

maryam-saeidi · 2025-04-04T10:32:36Z

Summary

This PR allows adding labels to the captureError function, similar to what we have in Node.js agent:
https://www.elastic.co/guide/en/apm/agent/nodejs/current/agent-api.html#apm-capture-error

Example usage:

apm.captureError(error, {
      labels: {
        errorType: 'ToastError',
      },
    });

david-luna

@maryam-saeidi thanks for your contribution. In addition to my comments I think the only thing left is to update the docs. I've checked and the right place for it is in /docs/reference/agent-api.md. There is a section with the API description.

packages/rum/src/apm-base.js

packages/rum/src/index.d.ts

vigneshshanmugam

LGTM, Could you also add docs for this new option as david pointed out.

packages/rum/src/apm-base.js

kpatticha · 2025-04-08T10:02:21Z

@maryam-saeidi what would be the best way to test it locally?

david-luna · 2025-04-08T12:26:18Z

There is a build error in docs unrelated to this change. However the documentation is rendered properly for the apm.captureError() API.
Link: https://docs-v3-preview.elastic.dev/elastic/apm-agent-rum-js/pull/1594/reference/agent-api#capture-error

Build error seems to be related to a cross-link refering to the APM server

Error: 'reference/ingestion-tools/observability/apm.md' is not a valid link in the 'docs-content' cross link index: https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/docs-content/main/links.json
    ┌─[/github/workspace/docs/reference/index.md]
    │
 39 │ APM Agents work in conjunction with the [APM Server](docs-content://reference/ingestion-tools/observability/apm.md), [Elasticsearch](docs-content://get-started/index.md), and [Kibana](docs-content://get-started/the-stack.md). The [APM Guide](docs-content://reference/ingestion-tools/observability/apm.md) provides details on how these components work together, and provides a matrix outlining [Agent and Server compatibility](docs-content://solutions/observability/apps/apm-agent-compatibility.md).

@colleenmcginnis do you know what might be happening here? is it possible that docset.yml needs a reference to APmM server and the link needs to be changed?

The error refers to a link

APM Agents work in conjunction with the [APM Server](docs-content://reference/ingestion-tools/observability/apm.md)

but it was changed in #1592 so maybe there is caching involved?

colleenmcginnis · 2025-04-08T13:40:41Z

@colleenmcginnis do you know what might be happening here? is it possible that docset.yml needs a reference to APmM server and the link needs to be changed?

It looks like this branch is two commits behind elastic:main (maryam-saeidi/apm-agent-rum-js@1591-support-labels-in-capturing-errors...elastic:apm-agent-rum-js:main) and the changes in #1592 is one of the two missing commits.

@maryam-saeidi can you catch up your branch to elastic:main to get the docs build to pass?

maryam-saeidi · 2025-04-08T15:37:04Z

@maryam-saeidi what would be the best way to test it locally?

We need to build this branch and then link the package in Kibana locally.

## Summary Updating apm-rum packages mostly to use this feature: elastic/apm-agent-rum-js#1594 Changes |Package|Previous version|Current version|Change log ([PR](https://github.com/elastic/apm-agent-rum-js/pull/1599/files))| |---|---|---|---| |@elastic/apm-rum|^5.16.3|^5.17.0|add support for adding labels to captured errors ([#1594](https://github.com/elastic/apm-agent-rum-js/pull/1594))| |@elastic/apm-rum-core|^5.22.1|^5.23.0|add support for adding labels to captured errors ([#1594](https://github.com/elastic/apm-agent-rum-js/pull/1594))| |@elastic/apm-rum-react|^2.0.5|^2.0.6|version bump only for package @elastic/apm-rum-react|

# Backport This will backport the following commits from `main` to `8.x`: - [Update apm-rum packages (#217800)](#217800)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport)

Closes elastic/observability-dev#4022 ## Summary In this PR, we are capturing toast errors using apm-rum: https://github.com/user-attachments/assets/b61529f9-ab8e-4171-9042-0884e11eb385 ErrorType is available in labels which this feature was added to the rum agent in this [PR](elastic/apm-agent-rum-js#1594). ### 🧪 How to test Add the following to your kibana.yml file: ``` elastic.apm.active: true elastic.apm.transactionSampleRate: 1.0 elastic.apm.environment: yourName <-- Change to your name ``` <details> <summary>Throw a toast error</summary> Add this code to a page as [alerts page](https://github.com/elastic/kibana/blob/main/x-pack/solutions/observability/plugins/observability/public/pages/alerts/alerts.tsx) and visit http://localhost:5601/kibana/app/observability/alerts ``` useEffect(() => { const error = new Error('Mary test error > toasts.addError'); toasts.addError(error, { title: 'Testing error toast', toastMessage: error.message }); toasts.addDanger('Testing danger toast'); }, []); ``` </details> Then visit [kibana-cloud-apm.elastic.dev](https://kibana-cloud-apm.elastic.dev/app/apm/services/kibana-frontend/errors?comparisonEnabled=true&environment=ENVIRONMENT_ALL&kuery=&latencyAggregationType=avg&offset=1d&rangeFrom=now-1h&rangeTo=now&serviceGroup=&transactionType=page-load) filtered for `yourName` in the environment.

## Summary Updating apm-rum packages mostly to use this feature: elastic/apm-agent-rum-js#1594 Changes |Package|Previous version|Current version|Change log ([PR](https://github.com/elastic/apm-agent-rum-js/pull/1599/files))| |---|---|---|---| |@elastic/apm-rum|^5.16.3|^5.17.0|add support for adding labels to captured errors ([elastic#1594](https://github.com/elastic/apm-agent-rum-js/pull/1594))| |@elastic/apm-rum-core|^5.22.1|^5.23.0|add support for adding labels to captured errors ([elastic#1594](https://github.com/elastic/apm-agent-rum-js/pull/1594))| |@elastic/apm-rum-react|^2.0.5|^2.0.6|version bump only for package @elastic/apm-rum-react| (cherry picked from commit a616a40) # Conflicts: # package.json

# Backport This will backport the following commits from `main` to `9.0`: - [Update apm-rum packages (#217800)](#217800)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport)

Closes elastic/observability-dev#4022 ## Summary In this PR, we are capturing toast errors using apm-rum: https://github.com/user-attachments/assets/b61529f9-ab8e-4171-9042-0884e11eb385 ErrorType is available in labels which this feature was added to the rum agent in this [PR](elastic/apm-agent-rum-js#1594). ### 🧪 How to test Add the following to your kibana.yml file: ``` elastic.apm.active: true elastic.apm.transactionSampleRate: 1.0 elastic.apm.environment: yourName <-- Change to your name ``` <details> <summary>Throw a toast error</summary> Add this code to a page as [alerts page](https://github.com/elastic/kibana/blob/main/x-pack/solutions/observability/plugins/observability/public/pages/alerts/alerts.tsx) and visit http://localhost:5601/kibana/app/observability/alerts ``` useEffect(() => { const error = new Error('Mary test error > toasts.addError'); toasts.addError(error, { title: 'Testing error toast', toastMessage: error.message }); toasts.addDanger('Testing danger toast'); }, []); ``` </details> Then visit [kibana-cloud-apm.elastic.dev](https://kibana-cloud-apm.elastic.dev/app/apm/services/kibana-frontend/errors?comparisonEnabled=true&environment=ENVIRONMENT_ALL&kuery=&latencyAggregationType=avg&offset=1d&rangeFrom=now-1h&rangeTo=now&serviceGroup=&transactionType=page-load) filtered for `yourName` in the environment. (cherry picked from commit ae9e5d6) # Conflicts: # src/core/packages/notifications/browser-internal/src/toasts/toasts_api.tsx

Closes elastic/observability-dev#4463 ## Summary Since we now have support for error labels in RUM ([PR](elastic/apm-agent-rum-js#1594)), this PR changes the way that we report rum errors to use labels similar to what we've done for toast errors ([PR](#217948)). https://github.com/user-attachments/assets/87a06ceb-705c-4c6e-ab26-d3e5874fe5ad ### ⚠️ Note In local development, the error is captured twice because react bubbles up the error, but it does not happen in production: ([doc](https://react.dev/reference/react/Component#componentdidcatch-caveats)) > Production and development builds of React slightly differ in the way componentDidCatch handles errors. In development, the errors will bubble up to window, which means that any window.onerror or window.addEventListener('error', callback) will intercept the errors that have been caught by componentDidCatch. In production, instead, the errors will not bubble up, which means any ancestor error handler will only receive errors not explicitly caught by componentDidCatch. ### 🧪 How to test Add the following to your kibana.yml file: ``` elastic.apm.active: true elastic.apm.transactionSampleRate: 1.0 elastic.apm.environment: yourName <-- Change to your name ``` <details> <summary>Throw a fatal react error</summary> Throw an error in the [alerts page](https://github.com/elastic/kibana/blob/main/x-pack/solutions/observability/plugins/observability/public/pages/alerts/alerts.tsx) and visit http://localhost:5601/kibana/app/observability/alerts </details> Then visit [kibana-cloud-apm.elastic.dev](https://kibana-cloud-apm.elastic.dev/app/apm/services/kibana-frontend/errors?comparisonEnabled=true&environment=ENVIRONMENT_ALL&kuery=&latencyAggregationType=avg&offset=1d&rangeFrom=now-1h&rangeTo=now&serviceGroup=&transactionType=page-load) filtered for `yourName` in the environment.

Closes elastic/observability-dev#4463 ## Summary Since we now have support for error labels in RUM ([PR](elastic/apm-agent-rum-js#1594)), this PR changes the way that we report rum errors to use labels similar to what we've done for toast errors ([PR](elastic#217948)). https://github.com/user-attachments/assets/87a06ceb-705c-4c6e-ab26-d3e5874fe5ad ### ⚠️ Note In local development, the error is captured twice because react bubbles up the error, but it does not happen in production: ([doc](https://react.dev/reference/react/Component#componentdidcatch-caveats)) > Production and development builds of React slightly differ in the way componentDidCatch handles errors. In development, the errors will bubble up to window, which means that any window.onerror or window.addEventListener('error', callback) will intercept the errors that have been caught by componentDidCatch. In production, instead, the errors will not bubble up, which means any ancestor error handler will only receive errors not explicitly caught by componentDidCatch. ### 🧪 How to test Add the following to your kibana.yml file: ``` elastic.apm.active: true elastic.apm.transactionSampleRate: 1.0 elastic.apm.environment: yourName <-- Change to your name ``` <details> <summary>Throw a fatal react error</summary> Throw an error in the [alerts page](https://github.com/elastic/kibana/blob/main/x-pack/solutions/observability/plugins/observability/public/pages/alerts/alerts.tsx) and visit http://localhost:5601/kibana/app/observability/alerts </details> Then visit [kibana-cloud-apm.elastic.dev](https://kibana-cloud-apm.elastic.dev/app/apm/services/kibana-frontend/errors?comparisonEnabled=true&environment=ENVIRONMENT_ALL&kuery=&latencyAggregationType=avg&offset=1d&rangeFrom=now-1h&rangeTo=now&serviceGroup=&transactionType=page-load) filtered for `yourName` in the environment.

Closes elastic/observability-dev#4463 ## Summary Since we now have support for error labels in RUM ([PR](elastic/apm-agent-rum-js#1594)), this PR changes the way that we report rum errors to use labels similar to what we've done for toast errors ([PR](elastic#217948)). https://github.com/user-attachments/assets/87a06ceb-705c-4c6e-ab26-d3e5874fe5ad ### ⚠️ Note In local development, the error is captured twice because react bubbles up the error, but it does not happen in production: ([doc](https://react.dev/reference/react/Component#componentdidcatch-caveats)) > Production and development builds of React slightly differ in the way componentDidCatch handles errors. In development, the errors will bubble up to window, which means that any window.onerror or window.addEventListener('error', callback) will intercept the errors that have been caught by componentDidCatch. In production, instead, the errors will not bubble up, which means any ancestor error handler will only receive errors not explicitly caught by componentDidCatch. ### 🧪 How to test Add the following to your kibana.yml file: ``` elastic.apm.active: true elastic.apm.transactionSampleRate: 1.0 elastic.apm.environment: yourName <-- Change to your name ``` <details> <summary>Throw a fatal react error</summary> Throw an error in the [alerts page](https://github.com/elastic/kibana/blob/main/x-pack/solutions/observability/plugins/observability/public/pages/alerts/alerts.tsx) and visit http://localhost:5601/kibana/app/observability/alerts </details> Then visit [kibana-cloud-apm.elastic.dev](https://kibana-cloud-apm.elastic.dev/app/apm/services/kibana-frontend/errors?comparisonEnabled=true&environment=ENVIRONMENT_ALL&kuery=&latencyAggregationType=avg&offset=1d&rangeFrom=now-1h&rangeTo=now&serviceGroup=&transactionType=page-load) filtered for `yourName` in the environment. (cherry picked from commit cea253d)

# Backport This will backport the following commits from `main` to `8.19`: - [Use RUM label for fatal react errors (#218846)](#218846)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport)  Co-authored-by: Maryam Saeidi <[email protected]>

maryam-saeidi added 3 commits April 4, 2025 12:19

feat: add labels to captured errors

f8383aa

chore: add test for rum package

cdb34b1

chore: add test for error-logging

3329c78

maryam-saeidi self-assigned this Apr 7, 2025

maryam-saeidi marked this pull request as ready for review April 7, 2025 10:30

maryam-saeidi requested a review from david-luna April 7, 2025 10:31

david-luna reviewed Apr 7, 2025

View reviewed changes

packages/rum/src/apm-base.js Outdated Show resolved Hide resolved

packages/rum/src/index.d.ts Outdated Show resolved Hide resolved

vigneshshanmugam previously approved these changes Apr 7, 2025

View reviewed changes

packages/rum/src/apm-base.js Outdated Show resolved Hide resolved

packages/rum/src/apm-base.js Outdated Show resolved Hide resolved

maryam-saeidi added 2 commits April 8, 2025 09:55

chore: change opt to opts

4506086

chore: add doc

c603449

maryam-saeidi dismissed vigneshshanmugam’s stale review via c603449 April 8, 2025 08:14

david-luna approved these changes Apr 8, 2025

View reviewed changes

Merge branch 'elastic:main' into 1591-support-labels-in-capturing-errors

979760f

david-luna merged commit 3d1ce71 into elastic:main Apr 8, 2025
20 checks passed

david-luna mentioned this pull request Apr 8, 2025

feat(rum-core): support labelling of errors #1414

Closed

maryam-saeidi deleted the 1591-support-labels-in-capturing-errors branch April 8, 2025 16:26

david-luna mentioned this pull request Apr 8, 2025

chore: update docs #1597

Merged

maryam-saeidi mentioned this pull request Apr 10, 2025

Update apm-rum packages elastic/kibana#217800

Merged

maryam-saeidi mentioned this pull request Apr 11, 2025

Track toast errors using apm-rum elastic/kibana#217948

Merged

maryam-saeidi mentioned this pull request Apr 22, 2025

Use RUM label for fatal react errors elastic/kibana#218846

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add support for adding labels to captured errors #1594

feat: add support for adding labels to captured errors #1594

Uh oh!

maryam-saeidi commented Apr 4, 2025

Uh oh!

david-luna left a comment

Uh oh!

Uh oh!

Uh oh!

vigneshshanmugam left a comment

Uh oh!

Uh oh!

Uh oh!

kpatticha commented Apr 8, 2025

Uh oh!

david-luna commented Apr 8, 2025 •

edited

Loading

Uh oh!

colleenmcginnis commented Apr 8, 2025

Uh oh!

maryam-saeidi commented Apr 8, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

feat: add support for adding labels to captured errors #1594

feat: add support for adding labels to captured errors #1594

Uh oh!

Conversation

maryam-saeidi commented Apr 4, 2025

Summary

Uh oh!

david-luna left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vigneshshanmugam left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kpatticha commented Apr 8, 2025

Uh oh!

david-luna commented Apr 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

colleenmcginnis commented Apr 8, 2025

Uh oh!

maryam-saeidi commented Apr 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

david-luna commented Apr 8, 2025 •

edited

Loading

maryam-saeidi commented Apr 8, 2025 •

edited

Loading